/

values

The values:​* stages return string values, typically document field values.

You can use the following values stages in your analysis requests:

values:​composite

Aggregats multiple lists of values.

values:​from​Documents

For each document, retrieves one or more values collected by the value​Collector of your choice.

values:​unique

Outputs the unique values found on the list of values you provide.

values:​reference

References the results of another values:​* stage defined in the request.

values:​composite

Aggregates multiple lists of values.

{
  "type": "values:composite",
  "operator": "OR",
  "values": []
}

operator

Type
string
Default
"OR"
Constraints
one of [OR, AND]
Required
no

The composition method to apply.

The operator property supports the following values:

O​R

Returns the union of input value lists. The output contains values that appear in at least one input list.

A​N​D

Returns the intersection of input value lists. The output contains values that appear in all input lists.

values

Type
array of values
Default
[]
Required
no

The value lists to combine.

values:​from​Documents

Returns one or more values for each document from the documents list you provide. 

{
  "type": "values:fromDocuments",
  "documents": {
    "type": "documents:reference",
    "auto": true
  },
  "multipleValues": "REQUIRE_EXACTLY_ONE",
  "threads": "auto",
  "valueCollector": null
}

This stage delegates the extraction of values from documents to the value​Collector you provide. For example, you can use the value​Collector:​from​Content​Field to retrieve values of one of the documents' content fields.

This stage returns a list of document values index-aligned with the list of input documents. If you set this stage to collect multiple values per document, each entry of the output list will be a list of values.

For example, the following request collects a list of the title field values for the first 5 documents matching the photon query. 

{
  "stages": {
    "values": {
      "type": "values:fromDocuments",
      "documents": {
        "type" : "documents:byQuery",
        "limit": 5,
        "query": {
          "type": "query:string",
          "query": "photon"
        }
      },
      "valueCollector": {
        "type": "valueCollector:fromContentField",
        "fieldName": "title"
      },
      "multipleValues": "REQUIRE_EXACTLY_ONE"
    }
  }
}

The result of the above request, on the reference Arxiv index:

{
  "result" : {
    "values" : {
      "values" : [
        "Photons, Photon Jets and Dark Photons at 750 GeV and Beyond",
        "Physics Opportunities at a Photon-Photon Collider",
        "Two-Photon Processes and Photon Structure",
        "Photon-hadron and photon-photon collisions in ALICE",
        "Photon Aided and Inhibited Tunneling of Photons"
      ]
    }
  }
}

Note that for multivalued fields, the response contains a list of values for each document. Here is a similar request, collecting all values of the multivalued category field: 

{
  "stages": {
    "values": {
      "type": "values:fromDocuments",
      "documents": {
        "type" : "documents:byQuery",
        "limit": 5,
        "query": {
          "type": "query:string",
          "query": "photon"
        }
      },
      "valueCollector": {
        "type": "valueCollector:fromContentField",
        "fieldName": "category"
      },
      "multipleValues": "COLLECT_ALL"
    }
  }
}

The result of the above request, on the reference Arxiv index:

{
  "result" : {
    "values" : {
      "values" : [
        [
          "hep-ph",
          "hep-ex"
        ],
        [
          "hep-ph"
        ],
        [
          "hep-ph"
        ],
        [
          "nucl-ex",
          "hep-ex"
        ],
        [
          "quant-ph",
          "physics.optics"
        ]
      ]
    }
  }
}

documents

Type
documents
Default
{
  "type": "documents:reference",
  "auto": true
}
Required
no

The documents from which to collect the values.

multiple​Values

Type
string
Default
"REQUIRE_EXACTLY_ONE"
Constraints
one of [COLLECT_FIRST, REQUIRE_EXACTLY_ONE, COLLECT_ALL]
Required
no

Configures the behaviour of this stage when the value collector returns multiple values.

The multiple​Values property supports the following values:

C​O​L​L​E​C​T_​F​I​R​S​T

Retrieve and return only the first value, ignoring the possible subsequent values the collector may return for the document. The response will contain a flat array of values, one value for each input document.

R​E​Q​U​I​R​E_​E​X​A​C​T​L​Y_​O​N​E

Retrieve and return only the first value. If the collector returns more than value, this option causes the request to fail. The response will contain a flat array of values, one value for each input document.

C​O​L​L​E​C​T_​A​L​L

Retrieve and return all values. The response will contain an array of arrays of values. An empty array of values is returned for documents which have no associated value for the requested field.

threads

Type
threads
Default
auto
Required
no

The number of CPU threads used for computing aggregations.

value​Collector

Type
valueCollector
Default
null
Required
yes

The value​Collector to use to collect values from each document. Use the value​Collector:​from​Content​Field to retrieve values of one of the documents' content fields.

values:​unique

Outputs the unique values found on the list of values you provide.

{
  "type": "values:unique",
  "labelFilter": {
    "type": "labelFilter:acceptAll"
  },
  "values": {
    "type": "values:reference",
    "auto": true
  }
}

The output values are sorted in natural order.

label​Filter

Type
labelFilter
Default
{
  "type": "labelFilter:acceptAll"
}
Required
no

The value filter to apply to each unique value.

values

Type
values
Default
{
  "type": "values:reference",
  "auto": true
}
Required
no

The values to convert to the list of unique values.

Consumers of values:​*

The following stages and components take values:​* as input:

Stage or component Property
clusters:​by​Values
  • values
    • documents:​contrast​Score
  • document​Timestamps
  • context​Timestamps
    • matrix:​value​Similarity​From​Document​Similarities
  • values
  • document​Values
    • values:​composite
  • values
    • values:​unique
  • values
    • vectors:​for​Document​Field​Values
  • source​Values
  • values
    •