54 lines
3.4 KiB
Plaintext
54 lines
3.4 KiB
Plaintext
[[java-rest-high-x-pack-graph-explore]]
|
|
=== X-Pack Graph explore API
|
|
|
|
[[java-rest-high-x-pack-graph-explore-execution]]
|
|
==== Initial request
|
|
|
|
Graph queries are executed using the `explore()` method:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/GraphDocumentationIT.java[x-pack-graph-explore-request]
|
|
--------------------------------------------------
|
|
<1> In this example we seed the exploration with a query to find messages mentioning the mysterious `projectx`
|
|
<2> What we want to discover in these messages are the ids of `participants` in the communications and the md5 hashes
|
|
of any attached files. In each case, we want to find people or files that have had at least one document connecting them
|
|
to projectx.
|
|
<3> The next "hop" in the graph exploration is to find the people who have shared several messages with the people or files
|
|
discovered in the previous hop (the projectx conspirators). The `minDocCount` control is used here to ensure the people
|
|
discovered have had at least 5 communications with projectx entities. Note we could also supply a "guiding query" here e.g. a
|
|
date range to consider only recent communications but we pass null to consider all connections.
|
|
<4> Finally we call the graph explore API with the GraphExploreRequest object.
|
|
|
|
|
|
==== Response
|
|
|
|
Graph responses consist of Vertex and Connection objects (aka "nodes" and "edges" respectively):
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/GraphDocumentationIT.java[x-pack-graph-explore-response]
|
|
--------------------------------------------------
|
|
<1> Each Vertex is a unique term (a combination of fieldname and term value). The "hopDepth" property tells us at which point in the
|
|
requested exploration this term was first discovered.
|
|
<2> Each Connection is a pair of Vertex objects and includes a docCount property telling us how many times these two
|
|
Vertex terms have been sighted together
|
|
|
|
|
|
[[java-rest-high-x-pack-graph-expand-execution]]
|
|
==== Expanding a client-side Graph
|
|
|
|
Typically once an application has rendered an initial GraphExploreResponse as a collection of vertices and connecting lines (graph visualization toolkits such as D3, sigma.js or Keylines help here) the next step a user may want to do is "expand". This involves finding new vertices that might be connected to the existing ones currently shown.
|
|
|
|
To do this we use the same `explore` method but our request contains details about which vertices to expand from and which vertices to avoid re-discovering.
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/GraphDocumentationIT.java[x-pack-graph-explore-expand]
|
|
--------------------------------------------------
|
|
<1> Unlike the initial request we do not need to pass a starting query
|
|
<2> In the first hop which represents our "from" vertices we explicitly list the terms that we already have on-screen and want to expand by using the `addInclude` filter.
|
|
We can supply a boost for those terms that are considered more important to follow than others but here we select a common value of 1 for all.
|
|
<3> When defining the second hop which represents the "to" vertices we hope to discover we explicitly list the terms that we already know about using the `addExclude` filter
|
|
|