[DOCS] Expanding Graph API reference content here & removing it from x-pack-kibana.
Original commit: elastic/x-pack-elasticsearch@89bce85e55
This commit is contained in:
Deb Adair
parent
231634251f
commit
32a283c51d
|
|
@ -1,12 +0,0 @@
|
||||||
[role="xpack"]
|
|
||||||
[[graph-api]]
|
|
||||||
== Graph APIs
|
|
||||||
|
|
||||||
The Graph "explore" API is accessible via the
|
|
||||||
`/_xpack/graph/_explore` endpoint.
|
|
||||||
See {kibana-ref}/graph-api-explore.html[Explore API].
|
|
||||||
|
|
||||||
//* <<graph-api-explore>>
|
|
||||||
|
|
||||||
//TO-DO: Create a formatted API reference topic for explore:
|
|
||||||
//include::graph/explore.asciidoc[]
|
|
||||||
|
|
@ -1,128 +1,403 @@
|
||||||
[role="xpack"]
|
[role="xpack"]
|
||||||
[[graph-explore]]
|
[[graph-explore-api]]
|
||||||
=== Explore API
|
== Explore API
|
||||||
|
|
||||||
The graph explore API ...
|
The Graph explore API enables you to extract and summarize information about
|
||||||
|
the documents and terms in your Elasticsearch index.
|
||||||
|
|
||||||
==== Request
|
The easiest way to understand the behaviour of this API is to use the
|
||||||
|
Graph UI to explore connections. You can view the most recent request submitted
|
||||||
|
to the `_explore` endpoint from the *Last request* panel. For more information,
|
||||||
|
see {kibana-ref}/graph-getting-started.html[Getting Started with Graph].
|
||||||
|
|
||||||
|
For additional information about working with the explore API, see the Graph
|
||||||
|
{kibana-ref}/graph-troubleshooting.html[Troubleshooting] and
|
||||||
|
{kibana-ref}/graph-limitations.html[Limitations] topics.
|
||||||
|
|
||||||
|
[float]
|
||||||
|
=== Request
|
||||||
|
|
||||||
`POST <index>/_xpack/graph/_explore`
|
`POST <index>/_xpack/graph/_explore`
|
||||||
|
|
||||||
|
[float]
|
||||||
|
=== Description
|
||||||
|
|
||||||
==== Description
|
An initial request to the `_explore` API contains a seed query that identifies
|
||||||
|
the documents of interest and specifies the fields that define the vertices
|
||||||
|
and connections you want to include in the graph. Subsequent `_explore` requests
|
||||||
|
enable you to _spider out_ from one more vertices of interest. You can exclude
|
||||||
|
vertices that have already been returned.
|
||||||
|
|
||||||
After an initial search users typically want to review the results using a form
|
[float]
|
||||||
of graph visualization tool like the one in the Kibana Graph UI. Users will
|
=== Request Body
|
||||||
frequently then select one or more vertices of interest and ask to load more
|
|
||||||
vertices that may be connected to their current selection. In graph-speak,
|
|
||||||
this operation is often called _spidering_ or _spidering out_.
|
|
||||||
|
|
||||||
In order to spider out it is typically necessary to define two things:
|
|
||||||
|
|
||||||
* The set of vertices from which you would like to spider
|
|
||||||
* The set of vertices you already have in your workspace which you want to
|
|
||||||
avoid seeing again in results
|
|
||||||
|
|
||||||
These two pieces of information when passed to the graph explore API will
|
|
||||||
ensure you are returned new vertices that can be attached to the existing
|
|
||||||
selection.
|
|
||||||
|
|
||||||
The `include`and `exclude` clauses provide the essential features that enable
|
|
||||||
clients to progressively build up a picture of related information in their
|
|
||||||
workspace. The `include` clause is used to define the set of start points from
|
|
||||||
which users wish to spider. Include clauses can also be used to limit the end
|
|
||||||
points users wish to reach, thereby "filling in" some of the missing links
|
|
||||||
between existing vertices in their client-side workspace. The `exclude` clause
|
|
||||||
can be used to avoid the Graph API returning vertices already visible in a
|
|
||||||
client's workspace or perhaps could list undesirable vertices that the client
|
|
||||||
has blacklisted from their workspace and never wants to see returned.
|
|
||||||
|
|
||||||
//==== Path Parameters
|
|
||||||
|
|
||||||
//==== Query Parameters
|
|
||||||
|
|
||||||
==== Request Body
|
|
||||||
|
|
||||||
connections::
|
|
||||||
TBD. A list of fields is provided.
|
|
||||||
query:::
|
|
||||||
TBD. Optionally, a "guiding query" can be used to guide the API as it
|
|
||||||
explores connected terms.
|
|
||||||
vertices:::
|
|
||||||
TBD.
|
|
||||||
|
|
||||||
NOTE: Further "connections" can be nested inside the "connections" object to
|
|
||||||
continue exploring out the relationships in the data. Each level of nesting is
|
|
||||||
commonly referred to as a "hop" and proximity in a graph is often thought of in
|
|
||||||
terms of "hop depth".
|
|
||||||
|
|
||||||
controls::
|
|
||||||
TBD.
|
|
||||||
use_significance:::
|
|
||||||
TBD. The `use_significance` flag defaults to true and is used to filter
|
|
||||||
associated terms to only those that are significantly associated with our
|
|
||||||
query. The algorithm used to calculate significance are explained in the
|
|
||||||
documentation for the
|
|
||||||
{ref}/search-aggregations-bucket-significantterms-aggregation.html[significant_terms aggregation].
|
|
||||||
|
|
||||||
sample_size:::
|
|
||||||
TBD. Each "hop" considers a sample of the best-matching documents on each
|
|
||||||
shard (default is 100 documents). Using samples has the dual benefit of
|
|
||||||
keeping exploration focused on meaningfully-connected terms and improving
|
|
||||||
the speed of execution. Very small values (less than 50) may not provide
|
|
||||||
sufficient weight-of-evidence to identify significant connections between
|
|
||||||
terms while very large sample sizes may dilute the quality and be slow.
|
|
||||||
|
|
||||||
timeout:::
|
|
||||||
TBD. A `timeout` setting (expressed here in milliseconds) after which
|
|
||||||
exploration will be halted and results gathered so far are returned. This is
|
|
||||||
a best-effort approach to termination so may overrun if, for example, a long
|
|
||||||
pause is encountered while FieldData is loaded for a field.
|
|
||||||
|
|
||||||
sample_diversity:::
|
|
||||||
TBD. To avoid the top-matching documents sample being dominated by a single
|
|
||||||
source of results sometimes it can prove necessary to request diversity in
|
|
||||||
the sample. This is achieved by selecting a single-value field and a maximum
|
|
||||||
number of documents per value in that field. In this example we are
|
|
||||||
requiring that there are no more than 500 click documents from any one
|
|
||||||
department in the store. This might help us consider products from the
|
|
||||||
electronics, book and video departments whereas without this diversification
|
|
||||||
our results may be entirely dominated by the electronics department.
|
|
||||||
|
|
||||||
query::
|
query::
|
||||||
TBD. A query is used to "seed" the exploration. Any of the usual {es} query
|
A seed query that identifies the documents of interest. Can be any valid
|
||||||
syntax can be used here to identify the documents of interest.
|
Elasticsearch query. For example:
|
||||||
|
+
|
||||||
|
[source,js]
|
||||||
|
--------------------------------------------------
|
||||||
|
"query": {
|
||||||
|
"bool": {
|
||||||
|
"must": {
|
||||||
|
"match": {
|
||||||
|
"query.raw": "midi"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"filter": [
|
||||||
|
{
|
||||||
|
"range": {
|
||||||
|
"query_time": {
|
||||||
|
"gte": "2015-10-01 00:00:00"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
--------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
vertices::
|
vertices::
|
||||||
TBD. A list of fields is provided.
|
Specifies or more fields that contain the terms you want to include in the
|
||||||
exclude:::
|
graph as vertices. For example:
|
||||||
TBD. The `exclude` clause avoids returning specific terms.
|
+
|
||||||
field::: TBD
|
[source,js]
|
||||||
include:::
|
--------------------------------------------------
|
||||||
TBD. Lists the start points from which we want to spider using an `include`
|
"vertices": [
|
||||||
array of the terms of interest. Note that if you have an `include` clause,
|
{
|
||||||
there is no need to define a seed query - we are implicitly querying for
|
"field": "product"
|
||||||
documents that contain any of the terms listed in our include clauses.
|
}
|
||||||
Instead of passing plain strings in this array it is also possible to pass
|
]
|
||||||
objects with `term` and `boost` values to boost matches on certain terms
|
--------------------------------------------------
|
||||||
over others.
|
|
||||||
size:::
|
|
||||||
TBD. We can control the maximum number of vertex terms returned for each
|
|
||||||
field using the `size` property. (Default is 5).
|
|
||||||
min_doc_count:::
|
|
||||||
TBD. This property acts as a certainty threshold - just how many documents
|
|
||||||
have to contain a pair of terms before we consider this to be a useful
|
|
||||||
connection? (Default is 3).
|
|
||||||
shard_min_doc_count:::
|
|
||||||
TBD. This is an advanced setting - just how many documents on a shard have
|
|
||||||
to contain a pair of terms before we return this for global consideration?
|
|
||||||
(Default is 2).
|
|
||||||
|
|
||||||
//==== Authorization
|
field::: Identifies a field in the documents of interest.
|
||||||
|
include::: Identifies the terms of interest that form the starting points
|
||||||
|
from which you want to spider out. You do not have to specify a seed query
|
||||||
|
if you specify an include clause. The include clause implicitly querys for
|
||||||
|
documents that contain any of the listed terms listed.
|
||||||
|
In addition to specifying a simple array of strings, you can also pass
|
||||||
|
objects with `term` and `boost` values to boost matches on particular terms.
|
||||||
|
exclude:::
|
||||||
|
The `exclude` clause prevents the specified terms from being included in
|
||||||
|
the results.
|
||||||
|
size:::
|
||||||
|
Specifies the maximum number of vertex terms returned for each
|
||||||
|
field. Defaults to 5.
|
||||||
|
min_doc_count:::
|
||||||
|
Specifies how many documents must contain a pair of terms before it is
|
||||||
|
considered to be a useful connection. This setting acts as a certainty
|
||||||
|
threshold. Defaults to 3.
|
||||||
|
shard_min_doc_count:::
|
||||||
|
This advanced setting controls how many documents on a particular shard have
|
||||||
|
to contain a pair of terms before the connection is returned for global
|
||||||
|
consideration. Defaults to 2.
|
||||||
|
|
||||||
////
|
connections::
|
||||||
==== Examples
|
Specifies or more fields from which you want to extract terms that are
|
||||||
|
associated with the specified vertices. For example:
|
||||||
|
+
|
||||||
|
[source,js]
|
||||||
|
--------------------------------------------------
|
||||||
|
"connections": { <3>
|
||||||
|
"vertices": [
|
||||||
|
{
|
||||||
|
"field": "query.raw"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
--------------------------------------------------
|
||||||
|
+
|
||||||
|
NOTE: Connections can be nested inside the `connections` object to
|
||||||
|
explore additional relationships in the data. Each level of nesting is
|
||||||
|
considered a _hop_, and proximity within the graph is often described in
|
||||||
|
terms of _hop depth_.
|
||||||
|
|
||||||
TO-DO: Add link to example in Kibana Guide
|
query:::
|
||||||
|
An optional _guiding query_ that constrains the Graph API as it
|
||||||
|
explores connected terms. For example, you might want to direct the Graph
|
||||||
|
API to ignore older data by specifying a query that identifies recent
|
||||||
|
documents.
|
||||||
|
vertices:::
|
||||||
|
Contains the fields you are interested in. For example:
|
||||||
|
+
|
||||||
|
[source,js]
|
||||||
|
--------------------------------------------------
|
||||||
|
"vertices": [
|
||||||
|
{
|
||||||
|
"field": "query.raw",
|
||||||
|
"size": 5,
|
||||||
|
"min_doc_count": 10,
|
||||||
|
"shard_min_doc_count": 3
|
||||||
|
}
|
||||||
|
]
|
||||||
|
--------------------------------------------------
|
||||||
|
|
||||||
////
|
controls:: Direct the Graph API how to build the graph.
|
||||||
|
|
||||||
|
use_significance:::
|
||||||
|
The `use_significance` flag filters associated terms so only those that are
|
||||||
|
significantly associated with your query are included. For information about
|
||||||
|
the algorithm used to calculate significance, see the
|
||||||
|
{ref}/search-aggregations-bucket-significantterms-aggregation.html[significant_terms
|
||||||
|
aggregation]. Defaults to `true`.
|
||||||
|
sample_size:::
|
||||||
|
Each _hop_ considers a sample of the best-matching documents on each
|
||||||
|
shard. Using samples improves the speed of execution and keeps
|
||||||
|
exploration focused on meaningfully-connected terms. Very small values
|
||||||
|
(less than 50) might not provide sufficient weight-of-evidence to identify
|
||||||
|
significant connections between terms. Very large sample sizes can dilute
|
||||||
|
the quality of the results and increase execution times.
|
||||||
|
Defaults to 100 documents.
|
||||||
|
timeout:::
|
||||||
|
The length of time in milliseconds after which exploration will be halted
|
||||||
|
and the results gathered so far are returned. This timeout is honored on
|
||||||
|
a best-effort basis. Execution might overrun this timeout if, for example,
|
||||||
|
a long pause is encountered while FieldData is loaded for a field.
|
||||||
|
sample_diversity:::
|
||||||
|
To avoid the top-matching documents sample being dominated by a single
|
||||||
|
source of results, it is sometimes necessary to request diversity in
|
||||||
|
the sample. You can do this by selecting a single-value field and setting
|
||||||
|
a maximum number of documents per value for that field. For example:
|
||||||
|
+
|
||||||
|
[source,js]
|
||||||
|
--------------------------------------------------
|
||||||
|
"sample_diversity": {
|
||||||
|
"field": "category.raw",
|
||||||
|
"max_docs_per_value": 500
|
||||||
|
}
|
||||||
|
--------------------------------------------------
|
||||||
|
|
||||||
|
// [float]
|
||||||
|
// === Authorization
|
||||||
|
|
||||||
|
[float]
|
||||||
|
=== Examples
|
||||||
|
|
||||||
|
[float]
|
||||||
|
[[basic-search]]
|
||||||
|
==== Basic exploration
|
||||||
|
|
||||||
|
An initial search typically begins with a query to identify strongly related terms.
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
--------------------------------------------------
|
||||||
|
POST clicklogs/_xpack/graph/_explore
|
||||||
|
{
|
||||||
|
"query": { <1>
|
||||||
|
"match": {
|
||||||
|
"query.raw": "midi"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"vertices": [ <2>
|
||||||
|
{
|
||||||
|
"field": "product"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"connections": { <3>
|
||||||
|
"vertices": [
|
||||||
|
{
|
||||||
|
"field": "query.raw"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
--------------------------------------------------
|
||||||
|
// CONSOLE
|
||||||
|
<1> Seed the exploration with a query. This example is searching
|
||||||
|
clicklogs for people who searched for the term "midi".
|
||||||
|
<2> Identify the vertices to include in the graph. This example is looking for
|
||||||
|
product codes that are significantly associated with searches for "midi".
|
||||||
|
<3> Find the connections. This example is looking for other search
|
||||||
|
terms that led people to click on the products that are associated with
|
||||||
|
searches for "midi".
|
||||||
|
|
||||||
|
The response from the explore API looks like this:
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
--------------------------------------------------
|
||||||
|
{
|
||||||
|
"took": 0,
|
||||||
|
"timed_out": false,
|
||||||
|
"failures": [],
|
||||||
|
"vertices": [ <1>
|
||||||
|
{
|
||||||
|
"field": "query.raw",
|
||||||
|
"term": "midi cable",
|
||||||
|
"weight": 0.08745858139552132,
|
||||||
|
"depth": 1
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"field": "product",
|
||||||
|
"term": "8567446",
|
||||||
|
"weight": 0.13247784285434397,
|
||||||
|
"depth": 0
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"field": "product",
|
||||||
|
"term": "1112375",
|
||||||
|
"weight": 0.018600718471158982,
|
||||||
|
"depth": 0
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"field": "query.raw",
|
||||||
|
"term": "midi keyboard",
|
||||||
|
"weight": 0.04802242866755111,
|
||||||
|
"depth": 1
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"connections": [ <2>
|
||||||
|
{
|
||||||
|
"source": 0,
|
||||||
|
"target": 1,
|
||||||
|
"weight": 0.04802242866755111,
|
||||||
|
"doc_count": 13
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"source": 2,
|
||||||
|
"target": 3,
|
||||||
|
"weight": 0.08120623870976627,
|
||||||
|
"doc_count": 23
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
--------------------------------------------------
|
||||||
|
<1> An array of all of the vertices that were discovered. A vertex is an indexed
|
||||||
|
term, so the field and term value are provided. The `weight` attribute specifies
|
||||||
|
a significance score. The `depth` attribute specifies the hop-level at which
|
||||||
|
the term was first encountered.
|
||||||
|
<2> The connections between the vertices in the array. The `source` and `target`
|
||||||
|
properties are indexed into the vertices array and indicate which vertex term led
|
||||||
|
to the other as part of exploration. The `doc_count` value indicates how many
|
||||||
|
documents in the sample set contain this pairing of terms (this is
|
||||||
|
not a global count for all documents in the index).
|
||||||
|
|
||||||
|
[float]
|
||||||
|
[[optional-controls]]
|
||||||
|
==== Optional controls
|
||||||
|
|
||||||
|
The default settings are configured to remove noisy data and
|
||||||
|
get the "big picture" from your data. This example shows how to specify
|
||||||
|
additional parameters to influence how the graph is built.
|
||||||
|
|
||||||
|
For tips on tuning the settings for more detailed forensic evaluation where
|
||||||
|
every document could be of interest, see the
|
||||||
|
{kibana-ref}/troubleshooting.html[Troubleshooting] guide.
|
||||||
|
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
--------------------------------------------------
|
||||||
|
POST clicklogs/_xpack/graph/_explore
|
||||||
|
{
|
||||||
|
"query": {
|
||||||
|
"match": {
|
||||||
|
"query.raw": "midi"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"controls": {
|
||||||
|
"use_significance": false,<1>
|
||||||
|
"sample_size": 2000,<2>
|
||||||
|
"timeout": 2000,<3>
|
||||||
|
"sample_diversity": {<4>
|
||||||
|
"field": "category.raw",
|
||||||
|
"max_docs_per_value": 500
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"vertices": [
|
||||||
|
{
|
||||||
|
"field": "product",
|
||||||
|
"size": 5,<5>
|
||||||
|
"min_doc_count": 10,<6>
|
||||||
|
"shard_min_doc_count": 3<7>
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"connections": {
|
||||||
|
"query": {<8>
|
||||||
|
"bool": {
|
||||||
|
"filter": [
|
||||||
|
{
|
||||||
|
"range": {
|
||||||
|
"query_time": {
|
||||||
|
"gte": "2015-10-01 00:00:00"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"vertices": [
|
||||||
|
{
|
||||||
|
"field": "query.raw",
|
||||||
|
"size": 5,
|
||||||
|
"min_doc_count": 10,
|
||||||
|
"shard_min_doc_count": 3
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
--------------------------------------------------
|
||||||
|
// CONSOLE
|
||||||
|
<1> Disable `use_significance` to include all associated terms, not just the
|
||||||
|
ones that are significantly associated with the query.
|
||||||
|
<2> Increase the sample size to consider a larger set of documents on
|
||||||
|
each shard.
|
||||||
|
<3> Limit how long a graph request runs before returning results.
|
||||||
|
<4> Ensure diversity in the sample by setting a limit on the number of documents
|
||||||
|
per value in a particular single-value field, such as a category field.
|
||||||
|
<5> Control the maximum number of vertex terms returned for each field.
|
||||||
|
<6> Set a certainty threshold that specifies how many documents have to contain
|
||||||
|
a pair of terms before we consider it to be a useful connection.
|
||||||
|
<7> Specify how many documents on a shard have to contain a pair of terms before
|
||||||
|
the connection is returned for global consideration.
|
||||||
|
<8> Restrict which document are considered as you explore connected terms.
|
||||||
|
|
||||||
|
|
||||||
|
[float]
|
||||||
|
[[spider-search]]
|
||||||
|
==== Spidering operations
|
||||||
|
|
||||||
|
After an initial search, you typically want to select vertices of interest and
|
||||||
|
see what additional vertices are connected. In graph-speak, this operation is
|
||||||
|
referred to as "spidering". By submitting a series of requests, you can
|
||||||
|
progressively build a graph of related information.
|
||||||
|
|
||||||
|
To spider out, you need to specify two things:
|
||||||
|
|
||||||
|
* The set of vertices for which you want to find additional connections
|
||||||
|
* The set of vertices you already know about that you want to exclude from the
|
||||||
|
results of the spidering operation.
|
||||||
|
|
||||||
|
You specify this information using `include`and `exclude` clauses. For example,
|
||||||
|
the following request starts with the product `1854873` and spiders
|
||||||
|
out to find additional search terms associated with that product. The terms
|
||||||
|
"midi", "midi keyboard", and "synth" are excluded from the results.
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
--------------------------------------------------
|
||||||
|
POST clicklogs/_xpack/graph/_explore
|
||||||
|
{
|
||||||
|
"vertices": [
|
||||||
|
{
|
||||||
|
"field": "product",
|
||||||
|
"include": [ "1854873" ] <1>
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"connections": {
|
||||||
|
"vertices": [
|
||||||
|
{
|
||||||
|
"field": "query.raw",
|
||||||
|
"exclude": [ <2>
|
||||||
|
"midi keyboard",
|
||||||
|
"midi",
|
||||||
|
"synth"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
--------------------------------------------------
|
||||||
|
// CONSOLE
|
||||||
|
<1> The vertices you want to start from are specified
|
||||||
|
as an array of terms in an `include` clause.
|
||||||
|
<2> The `exclude` clause prevents terms you already know about from being
|
||||||
|
included in the results.
|
||||||
|
|
@ -4,120 +4,20 @@
|
||||||
|
|
||||||
[partintro]
|
[partintro]
|
||||||
--
|
--
|
||||||
{xpack} exposes a wide range of REST APIs to manage and monitor its features.
|
{xpack} exposes REST APIs that are used by the UI components and can be called
|
||||||
|
directly to configure and access {xpack} features.
|
||||||
|
|
||||||
* <<info-api, Info API>>
|
* <<info-api, Info API>>
|
||||||
//* <<security-api, Security APIs>>
|
* Graph <<graph-explore-api, Explore API>>
|
||||||
* <<watcher-api, Watcher APIs>>
|
|
||||||
* <<graph-api, Graph APIs>>
|
|
||||||
* <<ml-apis, Machine Learning APIs>>
|
* <<ml-apis, Machine Learning APIs>>
|
||||||
* <<ml-api-definitions, Definitions>>
|
* {xpack-ref}/security-api.html[Security APIs]
|
||||||
|
* <<watcher-api, Watcher APIs>>
|
||||||
--
|
--
|
||||||
|
|
||||||
[role="xpack"]
|
|
||||||
[[info-api]]
|
|
||||||
== Info API
|
|
||||||
|
|
||||||
The info API provides general information on the installed {xpack}. This
|
include::info.asciidoc[]
|
||||||
information includes:
|
include::graph/explore.asciidoc[]
|
||||||
|
|
||||||
* Build Information - including the build number and timestamp.
|
|
||||||
* License Information - basic information about the currently installed license.
|
|
||||||
* Features Information - The features that are currently enabled and available
|
|
||||||
under the current license.
|
|
||||||
|
|
||||||
The following example queries the info API:
|
|
||||||
|
|
||||||
[source,js]
|
|
||||||
------------------------------------------------------------
|
|
||||||
GET /_xpack
|
|
||||||
------------------------------------------------------------
|
|
||||||
// CONSOLE
|
|
||||||
|
|
||||||
Example response:
|
|
||||||
[source,js]
|
|
||||||
------------------------------------------------------------
|
|
||||||
{
|
|
||||||
"build" : {
|
|
||||||
"hash" : "2798b1a3ce779b3611bb53a0082d4d741e4d3168",
|
|
||||||
"date" : "2015-04-07T13:34:42Z"
|
|
||||||
},
|
|
||||||
"license" : {
|
|
||||||
"uid" : "893361dc-9749-4997-93cb-802e3dofh7aa",
|
|
||||||
"type" : "trial",
|
|
||||||
"mode" : "trial",
|
|
||||||
"status" : "active",
|
|
||||||
"expiry_date_in_millis" : 1914278399999
|
|
||||||
},
|
|
||||||
"features" : {
|
|
||||||
"graph" : {
|
|
||||||
"description" : "Graph Data Exploration for the Elastic Stack",
|
|
||||||
"available" : true,
|
|
||||||
"enabled" : true
|
|
||||||
},
|
|
||||||
"logstash" : {
|
|
||||||
"description" : "Logstash management component for X-Pack",
|
|
||||||
"available" : true,
|
|
||||||
"enabled" : true
|
|
||||||
},
|
|
||||||
"ml" : {
|
|
||||||
"description" : "Machine Learning for the Elastic Stack",
|
|
||||||
"available" : true,
|
|
||||||
"enabled" : true,
|
|
||||||
"native_code_info" : {
|
|
||||||
"version" : "6.0.0-alpha1-SNAPSHOT",
|
|
||||||
"build_hash" : "d081461967d61a"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"monitoring" : {
|
|
||||||
"description" : "Monitoring for the Elastic Stack",
|
|
||||||
"available" : true,
|
|
||||||
"enabled" : true
|
|
||||||
},
|
|
||||||
"security" : {
|
|
||||||
"description" : "Security for the Elastic Stack",
|
|
||||||
"available" : true,
|
|
||||||
"enabled" : true
|
|
||||||
},
|
|
||||||
"watcher" : {
|
|
||||||
"description" : "Alerting, Notification and Automation for the Elastic Stack",
|
|
||||||
"available" : true,
|
|
||||||
"enabled" : true
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"tagline" : "You know, for X"
|
|
||||||
}
|
|
||||||
------------------------------------------------------------
|
|
||||||
// TESTRESPONSE[s/"hash" : "2798b1a3ce779b3611bb53a0082d4d741e4d3168",/"hash" : "$body.build.hash",/]
|
|
||||||
// TESTRESPONSE[s/"date" : "2015-04-07T13:34:42Z"/"date" : "$body.build.date"/]
|
|
||||||
// TESTRESPONSE[s/"uid" : "893361dc-9749-4997-93cb-802e3dofh7aa",/"uid": "$body.license.uid",/]
|
|
||||||
// TESTRESPONSE[s/"expiry_date_in_millis" : 1914278399999/"expiry_date_in_millis" : "$body.license.expiry_date_in_millis"/]
|
|
||||||
// TESTRESPONSE[s/"version" : "6.0.0-alpha1-SNAPSHOT",/"version": "$body.features.ml.native_code_info.version",/]
|
|
||||||
// TESTRESPONSE[s/"build_hash" : "d081461967d61a"/"build_hash": "$body.features.ml.native_code_info.build_hash"/]
|
|
||||||
// So much s/// but at least we test that the layout is close to matching....
|
|
||||||
|
|
||||||
You can also control what information is returned using the `categories` and
|
|
||||||
`human` parameters.
|
|
||||||
|
|
||||||
The following example only returns the build and features information:
|
|
||||||
|
|
||||||
[source,js]
|
|
||||||
------------------------------------------------------------
|
|
||||||
GET /_xpack?categories=build,features
|
|
||||||
------------------------------------------------------------
|
|
||||||
// CONSOLE
|
|
||||||
|
|
||||||
The following example removes the descriptions from the response:
|
|
||||||
|
|
||||||
[source,js]
|
|
||||||
------------------------------------------------------------
|
|
||||||
GET /_xpack?human=false
|
|
||||||
------------------------------------------------------------
|
|
||||||
// CONSOLE
|
|
||||||
|
|
||||||
//include::security.asciidoc[]
|
|
||||||
|
|
||||||
include::watcher.asciidoc[]
|
|
||||||
include::graph.asciidoc[]
|
|
||||||
include::ml-api.asciidoc[]
|
include::ml-api.asciidoc[]
|
||||||
include::defs.asciidoc[]
|
// include::security.asciidoc[]
|
||||||
|
include::watcher.asciidoc[]
|
||||||
|
include::defs.asciidoc[]
|
||||||
|
|
@ -0,0 +1,100 @@
|
||||||
|
[role="xpack"]
|
||||||
|
[[info-api]]
|
||||||
|
== Info API
|
||||||
|
|
||||||
|
The info API provides general information on the installed {xpack}. This
|
||||||
|
information includes:
|
||||||
|
|
||||||
|
* Build Information - including the build number and timestamp.
|
||||||
|
* License Information - basic information about the currently installed license.
|
||||||
|
* Features Information - The features that are currently enabled and available
|
||||||
|
under the current license.
|
||||||
|
|
||||||
|
The following example queries the info API:
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
------------------------------------------------------------
|
||||||
|
GET /_xpack
|
||||||
|
------------------------------------------------------------
|
||||||
|
// CONSOLE
|
||||||
|
|
||||||
|
Example response:
|
||||||
|
[source,js]
|
||||||
|
------------------------------------------------------------
|
||||||
|
{
|
||||||
|
"build" : {
|
||||||
|
"hash" : "2798b1a3ce779b3611bb53a0082d4d741e4d3168",
|
||||||
|
"date" : "2015-04-07T13:34:42Z"
|
||||||
|
},
|
||||||
|
"license" : {
|
||||||
|
"uid" : "893361dc-9749-4997-93cb-802e3dofh7aa",
|
||||||
|
"type" : "trial",
|
||||||
|
"mode" : "trial",
|
||||||
|
"status" : "active",
|
||||||
|
"expiry_date_in_millis" : 1914278399999
|
||||||
|
},
|
||||||
|
"features" : {
|
||||||
|
"graph" : {
|
||||||
|
"description" : "Graph Data Exploration for the Elastic Stack",
|
||||||
|
"available" : true,
|
||||||
|
"enabled" : true
|
||||||
|
},
|
||||||
|
"logstash" : {
|
||||||
|
"description" : "Logstash management component for X-Pack",
|
||||||
|
"available" : true,
|
||||||
|
"enabled" : true
|
||||||
|
},
|
||||||
|
"ml" : {
|
||||||
|
"description" : "Machine Learning for the Elastic Stack",
|
||||||
|
"available" : true,
|
||||||
|
"enabled" : true,
|
||||||
|
"native_code_info" : {
|
||||||
|
"version" : "6.0.0-alpha1-SNAPSHOT",
|
||||||
|
"build_hash" : "d081461967d61a"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"monitoring" : {
|
||||||
|
"description" : "Monitoring for the Elastic Stack",
|
||||||
|
"available" : true,
|
||||||
|
"enabled" : true
|
||||||
|
},
|
||||||
|
"security" : {
|
||||||
|
"description" : "Security for the Elastic Stack",
|
||||||
|
"available" : true,
|
||||||
|
"enabled" : true
|
||||||
|
},
|
||||||
|
"watcher" : {
|
||||||
|
"description" : "Alerting, Notification and Automation for the Elastic Stack",
|
||||||
|
"available" : true,
|
||||||
|
"enabled" : true
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"tagline" : "You know, for X"
|
||||||
|
}
|
||||||
|
------------------------------------------------------------
|
||||||
|
// TESTRESPONSE[s/"hash" : "2798b1a3ce779b3611bb53a0082d4d741e4d3168",/"hash" : "$body.build.hash",/]
|
||||||
|
// TESTRESPONSE[s/"date" : "2015-04-07T13:34:42Z"/"date" : "$body.build.date"/]
|
||||||
|
// TESTRESPONSE[s/"uid" : "893361dc-9749-4997-93cb-802e3dofh7aa",/"uid": "$body.license.uid",/]
|
||||||
|
// TESTRESPONSE[s/"expiry_date_in_millis" : 1914278399999/"expiry_date_in_millis" : "$body.license.expiry_date_in_millis"/]
|
||||||
|
// TESTRESPONSE[s/"version" : "6.0.0-alpha1-SNAPSHOT",/"version": "$body.features.ml.native_code_info.version",/]
|
||||||
|
// TESTRESPONSE[s/"build_hash" : "d081461967d61a"/"build_hash": "$body.features.ml.native_code_info.build_hash"/]
|
||||||
|
// So much s/// but at least we test that the layout is close to matching....
|
||||||
|
|
||||||
|
You can also control what information is returned using the `categories` and
|
||||||
|
`human` parameters.
|
||||||
|
|
||||||
|
The following example only returns the build and features information:
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
------------------------------------------------------------
|
||||||
|
GET /_xpack?categories=build,features
|
||||||
|
------------------------------------------------------------
|
||||||
|
// CONSOLE
|
||||||
|
|
||||||
|
The following example removes the descriptions from the response:
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
------------------------------------------------------------
|
||||||
|
GET /_xpack?human=false
|
||||||
|
------------------------------------------------------------
|
||||||
|
// CONSOLE
|
||||||
|
|
@ -2,7 +2,9 @@
|
||||||
[[ml-apis]]
|
[[ml-apis]]
|
||||||
== Machine Learning APIs
|
== Machine Learning APIs
|
||||||
|
|
||||||
You can use APIs to perform the following {ml} activities:
|
You can use the following APIs to perform {ml} activities.
|
||||||
|
See <<ml-api-definitions, Definitions>> for the resource definitions used by the
|
||||||
|
machine learning APIs and in advanced job configuration options in Kibana.
|
||||||
|
|
||||||
[float]
|
[float]
|
||||||
[[ml-api-datafeed-endpoint]]
|
[[ml-api-datafeed-endpoint]]
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue