Request Templates
This section introduces request templates and why they can be useful to detach algorithm configuration from actual clustering requests.
As mentioned in the introduction, a clustering query is self-contained and must carry the three required elements: algorithm name, language and documents to be clustered. In practice, the first two elements will rarely change – once the algorithm for a particular task is chosen, it will probably remain constant for all clustering requests. In situations like this we can pull out the constant part of the query into a template and use basic composition with the body of a query to get the final request.
Another useful application of templates is to detach the algorithm and its configuration from the logic that queries the clustering service or to group different algorithms and their tuning variants under much easier to remember aliases.
How to create a request template?
Let's explain it by walking through a simple example. For a request body like the one shown below, we can pull out everything up to the documents section:
{
"language": "English",
"algorithm": "Lingo",
"parameters": {
"preprocessing": {
"phraseDfThreshold": 1,
"wordDfThreshold": 1
}
},
"documents": [
{ "field": "foo bar" },
{ "field": "bar" },
{ "field": "baz" }
]
}
Let's create a file called 04 foo.json
under DCS-relative path:
web/service/templates/04 foo.json
. The name (identifier)
of the template is embedded in the file name: it is foo
. The
number in front of the alphanumeric name is always stripped (but it is used
to sort the templates for display purposes).
{
"language": "English",
"algorithm": "Lingo",
"parameters": {
"preprocessing": {
"phraseDfThreshold": 1,
"wordDfThreshold": 1
}
}
}
The foo
template contains constant (but overrideable) elements
of our clustering query. Once the DCS is started we can see if the template
has been loaded by looking at the startup log message or by
running a GET query against the /list
endpoint:
...
"templates" : [
"frontend-default",
"lingo",
"stc",
"bkmeans",
"foo"
]
}
Armed with the template foo
we can now assemble a much simpler
clustering request containing just the documents to be clustered:
{
"documents": [
{ "field": "foo bar" },
{ "field": "bar" },
{ "field": "baz" }
]
}
When posting the documents for clustering, use the
template
request parameter to provide the the template name
(foo
in our case):
curl -X POST --header "Content-Type: text/json" --data-binary @template-request.json "http://localhost:8080/service/cluster?indent&template=foo"