solr/solr-ref-guide/src/stream-api.adoc

= Stream Request Handler API
:page-toclevels: 1
:page-tocclass: right
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

The `/stream` request handler, beyond just running a streaming expression, also
lets you find out what expressions are available to use and lets you control the
behavior of any registered Daemon processes.

NOTE: This API doesn't follow the v2 API structure. 




[[plugins]]
== PLUGINS: List all expressions registered

Lists out all the streaming expressions that have been registered and are available for use.  This includes both the default expressions registered by the StreamHandler and any that you have registered.

`/stream?action=PLUGINS`


=== PLUGINS Response

The response will list each expression registered and it's implementing class.

=== Examples using PLUGINS

*Input*

[source,text]
----
http://localhost:8983/solr/gettingstarted/stream?action=PLUGINS
----

*Output*

[source,json]
----
{
  "plugins":{
    "enumeratedDistribution":"org.apache.solr.client.solrj.io.eval.EnumeratedDistributionEvaluator",
    "year":"org.apache.solr.client.solrj.io.eval.TemporalEvaluatorYear",
    "lteq":"org.apache.solr.client.solrj.io.eval.LessThanEqualToEvaluator",
    "upper":"org.apache.solr.client.solrj.io.eval.UpperEvaluator",
    "commit":"org.apache.solr.client.solrj.io.stream.CommitStream",
    "echo":"org.apache.solr.client.solrj.io.stream.EchoStream"
}
----

[[list]]
== LIST: List Daemon processes

The <<stream-decorator-reference.adoc#daemon,daemon>> function allows you to wrap a streaming expression and run it at intervals to provide both continuous push and pull streaming.
This command lists out all the currently running daemon processes.


`/stream?action=LIST`

IMPORTANT: This command lists out all the daemon processed that are registered to a specific core that you are interacting with, not across the collection as a whole.
If you have a collection that consists of multiple shards or multiple replicas of those shards, each LIST command will bounce between the cores, returning different lists of processes.  It's recommended that for
managing daemon processes you create a collection with a single core and no replicas to host the daemon processes to ensure a single view.

=== LIST Response

The response will describe each daemon process on that specific core.

=== Examples using LIST
This assumes that you have registered a daemon process similar to the below simplistic example that reads a single
random document from the `gettingstarted` collection and then writes it back to the same collection every 10 seconds:

[source,text]
----
daemon(
  id="12345",
  runInterval="10000",
  update(gettingstarted,
    random(gettingstarted,
         q="*:*",
         rows="1"
    )
  )
)
----

*Input*

[source,text]
----
http://localhost:8983/solr/gettingstarted/stream?action=LIST
----

*Output*

[source,json]
----
{
  "result-set":{
    "docs":[{
        "startTime":1582820357008,
        "stopTime":0,
        "id":"12345",
        "state":"TIMED_WAITING",
        "iterations":421}
      ,{
        "EOF":true}]}}
----

This shows a single daemon process running under the id of 12345, and that it has been run 421 times.  Each process is a {java-javadocs}java/lang/Thread.html,
and the states are those of a Thread.

[[stop]]
== STOP: Stop a Daemon processes

`/stream?action=STOP&id=12345`

=== STOP Response

The response will either report back the stopping of daemon process, or report it wasn't found on the specific core that the request was routed to.

=== Examples using STOP

*Input*

[source,text]
----
http://localhost:8983/solr/gettingstarted/stream?action=STOP&id=12345
----

*Output*

[source,json]
----
{
  "result-set":{
    "docs":[{
        "DaemonOp":"Deamon:12345 stopped on gettingstarted_shard2_replica_n4"}
      ,{
        "EOF":true}]}}
----

Calling LIST again will now have the `stopTime` of the process recorded.

=== START Response

The response will either report back the stopping of daemon process, or report it wasn't found on the specific core that the request was routed to.

=== Examples using START

*Input*

[source,text]
----
http://localhost:8983/solr/gettingstarted/stream?action=START&id=12345
----

*Output*

[source,json]
----
{
  "result-set":{
    "docs":[{
        "DaemonOp":"Deamon:12345 started on gettingstarted_shard2_replica_n4"}
      ,{
        "EOF":true}]}}
----

The count of `iterations` is preserved through the STOP/START cycle.

[[kill]]
== KILL: Remove a Daemon process

`/stream?action=KILL&id=12345`

=== KILL Response

The response will either report back the stopping of daemon process, or report it wasn't found on the specific core that the request was routed to.

=== Examples using KILL

*Input*

[source,text]
----
http://localhost:8983/solr/gettingstarted/stream?action=KILL&id=12345
----

*Output*

[source,json]
----
{
  "result-set":{
    "docs":[{
        "DaemonOp":"Deamon:12345 killed on gettingstarted_shard2_replica_n4"}
      ,{
        "EOF":true}]}}
----

The daemon process will no longer be listed in subsequent LIST commands.