solr/solr-ref-guide/src/variables.adoc

= Variables
// 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.


This section of the user guide describes how to assign and visualize
variables with math expressions.

== The Let Expression

The `let` expression sets variables and returns
the value of the last variable by default. The output of any streaming expression or math expression can be set to a variable.

Below is a simple example setting three variables `a`, `b`,
and `c`. Variables `a` and `b` are set to arrays. The variable `c` is set
to the output of the `ebeAdd` function which performs element-by-element
addition of the two arrays.

[source,text]
----
let(a=array(1, 2, 3),
    b=array(10, 20, 30),
    c=ebeAdd(a, b))
----

In the response, notice that the last variable, `c`, is returned:

[source,json]
----
{
  "result-set": {
    "docs": [
      {
        "c": [
          11,
          22,
          33
        ]
      },
      {
        "EOF": true,
        "RESPONSE_TIME": 4
      }
    ]
  }
}
----

== Echoing Variables

All variables can be output by setting the `echo` variable to `true`.

[source,text]
----
let(echo=true,
    a=array(1, 2, 3),
    b=array(10, 20, 30),
    c=ebeAdd(a, b))
----

When this expression is sent to the `/stream` handler it
responds with:

[source,json]
----
{
  "result-set": {
    "docs": [
      {
        "a": [
          1,
          2,
          3
        ],
        "b": [
          10,
          20,
          30
        ],
        "c": [
          11,
          22,
          33
        ]
      },
      {
        "EOF": true,
        "RESPONSE_TIME": 0
      }
    ]
  }
}
----

A specific set of variables can be echoed by providing a comma-delimited list of variables to the `echo` parameter.
Because variables have been provided, the `true` value is assumed.

[source,text]
----
let(echo="a,b",
    a=array(1, 2, 3),
    b=array(10, 20, 30),
    c=ebeAdd(a, b))
----

When this expression is sent to the `/stream` handler it responds with:

[source,json]
----
{
  "result-set": {
    "docs": [
      {
        "a": [
          1,
          2,
          3
        ],
        "b": [
          10,
          20,
          30
        ]
      },
      {
        "EOF": true,
        "RESPONSE_TIME": 0
      }
    ]
  }
}
----

== Visualizing Variables

The `let` expression can also include a `zplot` expression that can be used to visualize the
variables.

In the example below the variables `a` and `b` are set to arrays. The `zplot` function
outputs the variables as `x` and `y` fields in the output.

[source,text]
----
let(a=array(1, 2, 3),
    b=array(10, 20, 30),
    zplot(x=a, y=b))
----

When this expression is sent to the `/stream` handler it responds with:

[source,json]
----
{
  "result-set": {
    "docs": [
      {
        "x": 1,
        "y": 10
      },
      {
        "x": 2,
        "y": 20
      },
      {
        "x": 3,
        "y": 30
      },
      {
        "EOF": true,
        "RESPONSE_TIME": 0
      }
    ]
  }
}
----

Using this approach variables can by visualized using Zeppelin-Solr. In the example below
the arrays are shown in table format.

image::images/math-expressions/variables.png[]

Once in table format we can plot the variables using one of the plotting or charting
visualizations. The example below shows variables plotted on a line chart:

image::images/math-expressions/variables1.png[]


== Caching Variables

Variables can be cached in-memory on the Solr node where the math expression
was run. A cached variable can then be used in future expressions. Any object
that can be set to a variable, including data structures and mathematical models, can
be cached in-memory for future use.

The `putCache` function adds a variable to the cache.

In the example below an array is cached in the workspace `workspace1`
and bound to the key `key1`.
The workspace allows different users to cache objects in their own workspace.
The `putCache` function returns the variable that was added to the cache.

[source,text]
----
let(a=array(1, 2, 3),
    b=array(10, 20, 30),
    c=ebeAdd(a, b),
    d=putCache(workspace1, key1, c))
----

When this expression is sent to the `/stream` handler it responds with:

[source,json]
----
{
  "result-set": {
    "docs": [
      {
        "d": [
          11,
          22,
          33
        ]
      },
      {
        "EOF": true,
        "RESPONSE_TIME": 11
      }
    ]
  }
}
----

The `getCache` function retrieves an object from the cache by its workspace and key.

In the example below the `getCache` function retrieves the array that was cached above and assigns it to variable `a`.

[source,text]
----
let(a=getCache(workspace1, key1))
----

When this expression is sent to the `/stream` handler it responds with:

[source,json]
----
{
  "result-set": {
    "docs": [
      {
        "a": [
          11,
          22,
          33
        ]
      },
      {
        "EOF": true,
        "RESPONSE_TIME": 11
      }
    ]
  }
}
----

The `listCache` function can be used to list the workspaces or the keys in a specific workspace.

In the example below `listCache` returns all the workspaces in the cache as an array of strings.

[source,text]
----
let(a=listCache())
----

When this expression is sent to the `/stream` handler it responds with:

[source,json]
----
{
  "result-set": {
    "docs": [
      {
        "a": [
          "workspace1"
        ]
      },
      {
        "EOF": true,
        "RESPONSE_TIME": 0
      }
    ]
  }
}
----


In the example below all the keys in a specific workspace are listed:

[source,text]
----
let(a=listCache(workspace1))
----

When this expression is sent to the `/stream` handler it responds with:

[source,json]
----
{
  "result-set": {
    "docs": [
      {
        "a": [
          "key1"
        ]
      },
      {
        "EOF": true,
        "RESPONSE_TIME": 0
      }
    ]
  }
}
----

The `removeCache` function can be used to remove a key from a specific
workspace. The `removeCache` function removes the key from the cache
and returns the object that was removed.

In the example below the array that was cached above is removed from the cache.

[source,text]
----
let(a=removeCache(workspace1, key1))
----

When this expression is sent to the `/stream` handler it responds with:

[source,json]
----
{
  "result-set": {
    "docs": [
      {
        "a": [
          11,
          22,
          33
        ]
      },
      {
        "EOF": true,
        "RESPONSE_TIME": 0
      }
    ]
  }
}
----