/

Variables

You can extract values of stage and component properties from the inside of your request into the variables section and reference specific variables inside the stage and component definitions.

Extracting the moving parts of your request into variables has several benefits:

  • Ease of viewing and editing. If you put the variables section at the top of your request, you will immediately its most important elements, which would otherwise be buried in a multi-line JSON object.

    Moreover, you can edit variable values using familiar GUI elements, such as text boxes or sliders in the request variables editor view of the JSON Sandbox app.

  • Documentation. You can optionally attach a human-readable name and comment to each variable. Such metadata can be useful if you share your request for other team members to use or modify.

  • No duplication. You may want to set certain properties inside the request, such as document selection and content retrieval limit, to the same value. You can accomplish this by referencing the same variable at multiple points of your request.

Using variables

To extract a stage or component property into a variable, perform the following steps:

  1. Add the variables top-level section to your request if needed.

  2. Define variables.

    For each variable you want to define, add a property to the variables section. The name of the property is the variable name, value of the property defines the variable.

    Variable name can be an arbitrary string. Variable definition is an object with the value property, for example: 

    {
  "variables": {
    "limit": {

      "value": 130

    }

  }
}

    You can document each variable using the name and comment properties:

    {
  "variables": {
    "limit": {
      "name": "Document count",

      "comment": "How many documents to select.",

      "value": 130
    }
  }
}

  3. Reference variables in stage or component body.

    To reference a variable value in a specific stage or component property, use an object containing the @var property equal to the name of the variable: 

    {
  "variables": {
    "limit": 130
  },
  "stages": {
    "documents": {
      "type": "documents:byQuery",
      "limit": {
        "@var": "limit"
      }
    }
  }
}

The following request selects a number of documents and fetches their content. It defines three variables: query, limit and display​Fields. 

{
  "variables": {
    "query": {
      "name": "Query",
      "comment": "The search query to execute.",
      "value": "photon"
    },
    "limit": {
      "name": "Max results",
      "comment": "The maximum number of search results to retrieve.",
      "value": 40
    },
    "displayFields": {
      "name": "Display fields",
      "comment": "Fields to display for each result document.",
      "value": [
        "title",
        "abstract",
        "author_name"
      ]
    }
  },
  "stages": {
    "documents": {
      "type": "documents:byQuery",
      "query": {
        "type": "query:string",
        "query": {
          "@var": "query"
        }
      },
      "limit": {
        "@var": "limit"
      }
    },
    "documentContent": {
      "type": "documentContent",
      "fields": {
        "type": "contentFields:grouped",
        "groups": [
          {
            "fields": {
              "@var": "displayFields"
            }
          }
        ]
      },
      "limit": {
        "@var": "limit"
      }
    }
  }
}

Notice how the request references the limit variable both in the documents and document​Content stage to keep both limit properties synchronized.

Variable groups

If your request contains a large number of variables, you can organize related variables into groups to make the request easier to navigate.

To organize variables into a group:

  1. In the variables section of your request, add an object-valued property with the following properties: 

    {
  "variables": {
    "queryConfiguration": {
      "name": "Query configuration",
      "comment": "Configures the search query",
      "variables": {

      }
    }
  }
}

  2. In the variables section of the group object, add the group's variables:

    {
  "variables": {
    "group": {
      "name": "Query configuration",
      "comment": "Search query and parameters configuration.",
      "variables": {

        "query": {

          "name": "Search query",
          "value": "data mining"
        },
        "filterQuery": {

          "name": "Additional querying condition",
          "value": "category:cs"
        },
        "limit": {

          "name": "Number of documents to return",
          "value": 100
        }
      }
    }
  }
}
Heads up, variable identifiers must be request-level unique!

Variable identifiers (keys in the variables JSON object) must be unique with respect to the whole request. Lingo4G server does not accept requests with variable identifiers duplicated across variable groups.

Limitations

Request variables currently have the following limitations:

  • Primitive and array values only. Currently, you can use variables to replace properties of the following types:

    • number
    • string
    • boolean
    • array of strings

    It is therefore not possible, for example, to extract the whole stage definition into a variable.